Repository navigation
Combat 4.1: Move damage formulas into combat.yml - #387
Merged
Merged
Conversation
The four formulas of DamageCalculator become named expressions in a new combat.yml with a default and a legacy preset, per-expression overrides, automatic migration of the old legacy-combat key, and a per-expression fallback to the preset when a formula is broken. Expressions are compiled through Formulas, which wraps Codex's string evaluation for now. It is temporary: Codex has no compile step yet, and it is about 1700x slower than the Java formulas on the calculator benchmark. It is to be replaced by Evaluator.compile once published. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FaEyTrDtJEM6YN1zxnDP6d
Replaces the temporary string-evaluating Formulas with Codex's CompiledExpression, reuses one argument array per expression in the calculator, and raises MIN_CORE_VERSION to 1.3.0-dev.2. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FaEyTrDtJEM6YN1zxnDP6d
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FaEyTrDtJEM6YN1zxnDP6d
… real reload - A '^' followed by a minus is rejected at load: Codex's parser can compute it wrongly without complaint. - pve_damage and pve_defense become pvp_pve_damage and pvp_pve_defense, since they are the PvP values when both sides are players. - CombatReloadTest goes through the plugin's real reload. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FaEyTrDtJEM6YN1zxnDP6d
Travja
marked this pull request as ready for review
November 18, 2026 02:41
DamageCalculator reused argument arrays to save an allocation per evaluation. Measured on the benchmark that saved nothing noticeable, and it made sharing a calculator between threads unsafe, which the stat snapshots (4.2) may want. Each evaluation now builds its own array. Adds a test that shares one calculator between eight threads. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FaEyTrDtJEM6YN1zxnDP6d
Resolves conflicts with 4.2 (stat snapshots) and 4.2b in EngineCfg (both sides added a field) and in the notes doc (both sides added a section and a status row). Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FaEyTrDtJEM6YN1zxnDP6d
This was referenced Nov 18, 2026
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #371. Part of #365.
The numeric formulas of
DamageCalculatorbecome four named expressions in a newcombat.yml, compiled once at load with Codex'sEvaluator.compileand evaluated per damage type of every hit. With the shipped default file the numbers are identical to today's, bit for bit. With thelegacypreset they are identical to today'slegacy-combat: true.devhas been merged into this branch (4.2 and 4.2b landed meanwhile). The conflicts were inEngineCfg(both sides added a field) and in the notes doc (both sides added a section and a status row); nothing else needed resolving, and the whole suite passes on the merged result.Stage inventory
What I read:
DamageCalculatorandDamageManager.onDamageRPGStart/handleDamageModifiers. Only formulas became expressions; rolls, events and ordering stay in Java.handleDamageModifiers)Rnd < dodge_rate && Rnd >= accuracy_rate;Dodgeevent; cancelRnd < crit_rate; modifier =CRITICAL_DAMAGEor 1 if that is 0pvpDamage = 1 + stat/100,pvpDefense = 1 + stat/100,penetration = 1 - stat/100,direct = 0/100(direct damage is switched off)block-rate-bonus,block-damage-bonus); roll; modifier1 - blockDamage/100; shield durability roll100/(level+1)Preevent, MythicMobs faction lookupcustom-cooldownmetadata or the stat's modifier; 1 for skill damagegetEnchantModifierdamage * pvp_pve_damage * crit * entity_type * faction * enchant * attack_power * block, attack power skipped for exempt eventsdamage-scalingdirect = scaled * direct_fraction; thenmax(0, scaled - direct)direct-damage(the subtraction stays in Java)max(0, defense * pvp_pve_defense * penetration)defense-valuemax(0, d * (1 - max(def/5, def - 4d/max(1, toughness+8)) * protection * 0.05));legacy-combat:max(0, d * (1 - def * protection * 0.01))legacy-combatdefense-mitigation, one text per presettotal + invulnerableProt < 0.001cancelsExitStage 4 is arithmetic too, but each line converts one stat into a modifier and lives in the stats-reading code, which 4.2 (stat caching) rewrote in parallel. I left it alone to keep this PR inside "formula evaluation and config loading". It is the obvious next candidate if you want more of it configurable.
combat.ymllayout and the full default fileTop level keys:
preset(defaultorlegacy) andexpressions(optional overrides, keyed by expression name). The shipped file lists each default expression commented out beside its documentation, so that thelegacypreset's difference stays visible.src/main/resources/combat.yml
Variables
Variables are bound by position in the order below (
CombatExpressionis the single source; a test checks it against the shipped file). Names use underscores because a hyphen is the minus operator.pvp_pve_damageandpvp_pve_defenseare the PvP values when both sides are players, hence the names.damage-scalingdamage,pvp_pve_damage,critical,entity_type,faction,enchant_protection,attack_power,blockdirect-damagedamage,directdefense-valuedefense,pvp_pve_defense,penetrationdefense-mitigationdamage,defense,protection,toughnessMigration
combat.ymldoes not exist, it is written from the shipped file withpreset:set from the oldcombat.legacy-combatkey ofengine.yml(truegiveslegacy;falseor absent givesdefault). When the old key was present, one line is logged:Moved 'combat.legacy-combat: X' from engine.yml to combat.yml (preset: P). The old key is now ignored.combat.ymlis never overwritten (the write uses create-new, so even a file that appears between the check and the write survives). Migration is idempotent: later loads change nothing and log nothing.engine.yml. The shippedengine.ymlno longer has the key; existing servers' files are left alone.Reload
CombatCfg.loadruns fromDivinity.setConfig(), right afterEngineCfg. The plugin's real reload (Divinity#reload, which goes throughConfigManager.setuptosetConfig) therefore re-readscombat.yml, and a migration on reload sees the old keyEngineCfghas just read. This is exercised byCombatReloadTest, which calls the realplugin.reload()under MockBukkit: edits to the preset and to expressions are picked up; an oldengine.ymlkey with nocombat.ymlmigrates to the matching preset; an existingcombat.ymlis kept and the old key ignored. I did not look for a command that triggers that reload from a player or console; I found only the per-modulereloadcommands.Failure behaviour
^followed by a minus (see below), or a result that is NaN or infinite for ordinary sample values is reported once, naming the key and the reason, and that one expression uses the chosen preset's text (the legacy preset falls back to legacy, not to default). The others are unaffected. An unknown preset name or an unknown expression key is reported once and ignored.x * 2^-1wrongly without complaining (defense * 2^-1gives -900 fordefense = 30; the right answer is 15). The old string evaluator gives the same wrong number, so it is not new inEvaluator.compile. Until it is fixed in Codex, any override in which^is followed (ignoring whitespace) by a minus is rejected at load, with a message telling the admin to bracket the exponent (2^(-1)), and falls back like any other invalid formula. Follow-up for the Codex repo: fix the unary-minus-after-^parse in Javaluator; the check inCombatFormulas(NEGATIVE_EXPONENT) can then be removed.Thread safety
DamageCalculatorholds no state between calls: every evaluation builds its own argument array, so one calculator can be shared between threads and kept across hits. TodayDamageManagerstill builds one per hit on the main thread (4.2 did not change that), so this is a guard against a future change rather than a fix for a current bug.CombatFormulasis immutable apart from one warn-once flag per expression, and Codex'sCompiledExpressionis thread-safe. An earlier revision of this PR reused argument arrays inside the calculator to avoid the allocation; that saved nothing measurable (see below) and made sharing a calculator unsafe, so it was removed.Benchmark
DamageCalculatorBenchmark(test sources, amain, not a test) sends the same pre-generated inputs throughReferenceDamageCalculator(the replaced Java formulas, verbatim) and through the configured calculator. A hit is one calculator and three damage types, two of them defended. Both give identical bits before timing starts. Median of 7 rounds per run, several runs on one machine:combat.yml,Evaluator.compile, array per call)That is roughly 450 ns against 30 ns per hit, which is ten evaluations at about 35 to 45 ns each. The configured formulas are faster than Javaluator's string evaluation (about 35 ns against about 3,400 ns per evaluation, as measured in Codex), which is what the compile step is for, but they are not faster than inlined Java. This is over the 1.5x this PR first aimed for, and it is accepted: 400 to 450 ns per hit is small against a full hit through
DamageManager, which is far more expensive (event firing, stat reads); I did not measure a full hit. The figures are calculator-only and the Java baseline is tiny because the JIT inlines it. For reference, a first version of this branch built on Codex's string evaluation, before it had a compile step, was about 1,700x slower.Allocating an argument array per evaluation instead of reusing one per calculator made no measurable difference: with reused arrays the configured side ran at 1.8M to 2.1M hits/s in the same session, with an array per call at 1.9M to 2.3M, which is inside the run-to-run noise. (The benchmark was not re-run after merging
dev; the calculator is unchanged by the merge.)What is deliberately not included
engine.yml.EngineCfg.LEGACY_COMBAT/Modifiers.legacyCombatswitch. It stays so the untouched legacy tests keep selecting the legacy preset (CombatCharacterizationTest,DamageCalculatorTest, and 4.2'sEntityStatSnapshotTestall rely on it); nothing in production sets it, and the oldengine.ymlkey is read only by migration, so a stalelegacy-combat: truecannot overridecombat.yml. Removal is Phase 5.Tests
CombatCharacterizationTestandDamageCalculatorTestare unmodified and pass.DependencyRequirementTest.minimumCodexVersion_...followsMIN_CORE_VERSIONto1.3.0-dev.2(the first Codex build withEvaluator.compile);1.3.0-dev.1is now asserted to be too old.CombatFormulasTest(25),CombatCfgTest(18) andCombatReloadTest(4).ReferenceDamageCalculatoris a verbatim copy of the old arithmetic), and one reused calculator equals it over 10,000 varied calls.2^-1,defense * 2^-1,defense * 2 ^ -1and other spellings, division by zero,0/0, empty, wrong type) fall back with one message naming the key, to the chosen preset's text; a formula that only breaks during a hit falls back for that hit and warns once.2^(-1)anddefense - 2^2are accepted.true,falseand absent; an existing file is never overwritten; idempotency; the old key ignored once the file exists; an unwritable folder; reload picks up preset and expression changes; an unparseable file, unknown preset and unknown key; the shipped file against the code.mvn testexit code 0, 289 run, 0 failures, 0 errors, 2 skipped (the two trident tests inVanillaWrapperListenerTest).Break-it checks (each reverted afterwards, files compared byte for byte)
defense-mitigationtextsCombatCharacterizationTestandDamageCalculatorTestamong them)protectionnot passed)combat.ymlCombatCfg.loadmoved beforeEngineCfginsetConfigreload_readsTheOldKeyFromEngineYmlBeforeMigrating)CombatCfg.loadremoved fromsetConfigCombatReloadTest)The break-it checks were run before
devwas merged in; the counts include only this PR's tests and the two existing calculator test classes. Two earlier rows about reused argument arrays were removed with that design.Open questions
None open from the review. Follow-up outside this PR: the Codex parser fix above, and Phase 5 removal of the deprecated legacy switch.
Generated by Claude Code